home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / rbbs_pc / rbbsdocs.zip / RBBSDOCS.20 < prev    next >
Text File  |  1990-11-05  |  21KB  |  426 lines
  1.  
  2.  
  3.  
  4.     RBBS-PC's STANDARD INTERFACE FOR PROTOCOL DRIVERS                      20-1
  5.  
  6.  
  7.     20. RBBS-PC's STANDARD INTERFACE FOR PROTOCOL DRIVERS
  8.     -----------------------------------------------------
  9.     RBBS-PC  includes  a  flexible  interface  for  implementing  file-transfer
  10.     protocols.  A  "protocol" for  the  exchange  of files  is  just  a set  of
  11.     cooperative  conventions that  allow two  different computer's  software to
  12.     transfer  files  between themselves.    RBBS-PC  supports four  "protocols"
  13.     within its own BASIC source code -- ASCII, Xmodem (checksum), Xmodem (CRC),
  14.     and 1K-Xmodem.  These are totally configurable by the SysOp when setting up
  15.     RBBS-PC.
  16.  
  17.     In addition to these four "protocols" and in order to  provide advocates of
  18.     specific  protocols   a  means  of   adding  their  particular   flavor  of
  19.     communications protocol to  RBBS-PC, a standard interface  has been created
  20.     so  that  "external" protocols  can be  installed  in RBBS-PC.   "External"
  21.     protocols are simply defined  as programs outside of RBBS-PC  which perform
  22.     the file transfer.
  23.  
  24.     Before calling "external" protocol drivers, RBBS-PC will do the following:
  25.  
  26.       1) verify that the file exists if the file is to be downloaded.
  27.       2) for uploads, verify that the file name requested is valid.
  28.       3) pass control of the communications port to the external protocol.
  29.  
  30.     RBBS-PC  will call  the  external protocol  drivers  either via  the  SHELL
  31.     command in BASIC or via a .BAT file.
  32.  
  33.     20.1 Parameters passed to a protocol driver
  34.     -------------------------------------------
  35.     RBBS-PC detects the installation of external file transfer protocols via an
  36.     optional RBBS-PC system  file whose default name is PROTO.DEF.   If no such
  37.     file  exists, only internal protocols  will be available  -- Ascii, Xmodem,
  38.     XmodemCRC, 1K-Xmodem.   This file may be  used to rename or  delete some or
  39.     all of  RBBS-PC's internal protocols.   If a PROTO.DEF file  exists, all of
  40.     RBBS-PC's internal  protocols must be  specified in it  as well.   Internal
  41.     protocols are NOT automatically included when a PROTO.DEF file exists!
  42.  
  43.     The protocol definition file  has thirteen (13) parameters passed  for each
  44.     external protocol defined for RBBS-PC.  Each parameter can be on a separate
  45.     line of  its own or all  parameters can be  on a single line  (separated by
  46.     commas).  The parameters passed for each protocol specified are:
  47.  
  48.          Parameter      Description
  49.  
  50.                1        Protocol Name
  51.                2        Security Level required to use protocol
  52.                3        Method to invoke protocol
  53.                4        Whether 8 bit connection required
  54.                5        Whether "reliable" connection required
  55.                6        Whether "batch" mode supported
  56.                7        Number of bytes in a block transferred
  57.                8        Indicate transfer always successful
  58.                9        Factor to estimate file transfer time
  59.               10        RBBS-PC "macro" to invoke before protocol
  60.               11        Method for checking transfer's success
  61.               12        Template to use for downloading
  62.               13        Template to use for uploading
  63.  
  64.     Protocol  Name  -- The  FIRST CHARACTER  is the  letter  by which  a caller
  65.     selects the protocol.   The prompt for the  selection of protocol  includes
  66.  
  67.  
  68.  
  69.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                    20-2
  70.  
  71.  
  72.     the protocol  name.  It is recommended that the  second character be ")" to
  73.     resemble the rest of the prompts in RBBS-PC, e.g. "Z)modem".   RBBS-PC will
  74.     normally put  each protocol on the  same line, separated by  a comma, until
  75.     the line gets too long.  The SysOp can control the placement of the line by
  76.     putting a  carriage return line feed at  the end of the  protocol name.  If
  77.     this  is done,  the  entire protocol  name  must be  in  parentheses.   For
  78.     example, instead of the prompt
  79.  
  80.     A)scii,X)modem,C)rcXmodem,Y)modem,N)one
  81.  
  82.     a SysOp may want the prompt to be
  83.  
  84.     A)scii (text files only)
  85.     X)modem checksum
  86.     C)rc Xmodem
  87.     Y)modem (1K Xmodem)
  88.     N - None (cancel)
  89.  
  90.     Then  the protocol definition file , PROTO.DEF, should be constructed using
  91.     quotes (to include the carriage return/line feed in the first parameter) as
  92.     follows:
  93.  
  94.     "A)scii (text files only)
  95.     ",...
  96.     "X)modem checksum
  97.     ",...
  98.     "C)rc Xmodem
  99.     ",...
  100.     "Y)modem (1K Xmodem)
  101.     ",...
  102.     "N - None (cancel)
  103.     ",...
  104.  
  105.     with the remaining 12 parameters put where "..." occurs.
  106.  
  107.     Security  Level --  This is  the minimum  security to  be able  to  use the
  108.     protocol being described.
  109.  
  110.     Method to  Invoke Protocol  -- A protocol  can be invoked  by one  of three
  111.     methods:
  112.              shell,
  113.              door, or
  114.              internal (S, D, or I).
  115.  
  116.     If "I" is specified, it must be immediately followed by a letter specifying
  117.     what internal  protocol to  use, where  the choices are  A, X,  C, Y,  or N
  118.     respectively for  Ascii, Xmodem, Xmodem CRC, 1K-X(Y)modem,  or None (cancel
  119.     transfer).  "IC" would  mean to use RBBS-PC's internal  Xmodem CRC.  If  no
  120.     protocol is specified equivalent  to the internal "None", RBBS-PC  will add
  121.     it.  If the letter N is used for a transfer protocol, another protocol must
  122.     be specified that is equivalent to "None".
  123.  
  124.     Whether to Require 8 Bit -- By  putting "8" in this parameter, the SysOp is
  125.     specifying that  the protocol  requires the  caller to be  able to  send or
  126.     receive 8 data bits.  If 8 data bits is required and the caller is not at 8
  127.     bit, RBBS-PC will prompt the caller to change to  8 bit in order to use the
  128.     protocol.
  129.  
  130.  
  131.  
  132.     RBBS-PC's STANDARD INTERFACE FOR PROTOCOL DRIVERS                      20-3
  133.  
  134.  
  135.     Whether  A Reliable  Connection  Is Required  --  By  putting "R"  in  this
  136.     parameter,  the SysOp is specifying that the  protocol will not be shown or
  137.     made available  to the caller unless the connections is reliable (i.e. such
  138.     as Microcom's MNP protocol that is built into many modems).
  139.  
  140.     Whether Batch is  supported -- By putting "B" in  this parameter, the SysOp
  141.     is  indicating that "batch" file  transfers are allowed  with the protocol.
  142.     "Batch" means a multi-file  download request will be processed  together.
  143.     RBBS-PC  enters  an  external  protocol  only  once  to  do  multiple  file
  144.     downloads.   RBBS-PC has been  tested with  such "batch" protocols  as Omen
  145.     Technologies' DSZ Zmodem, Megalink, and Sealink.
  146.  
  147.     Blocksize  -- This parameter  indicates the number  of bytes in  each block
  148.     transferred.   This is only used to inform the  caller the number of blocks
  149.     to expect when  downloading.  A zero in this  parameters will cause RBBS-PC
  150.     to report only the number of bytes to expect.  For Xmodem or XmodemCRC this
  151.     value would be 128.  For Ymodem this value would be 1024.
  152.  
  153.     Indicate Transfers Always Successful -- If there is no way for the protocol
  154.     to  inform RBBS-PC  if  a  transfer  was  successful, put  a  "F"  in  this
  155.     parameter, which stands  for "Fake" a success report.   This means that all
  156.     transfers will be regarded as successful.
  157.  
  158.     Zmodem  (DSZ)  used  in a  multi-tasking  DOS  environment  (where the  DOS
  159.     environment  variables are shared) and CLINK are examples of protocols that
  160.     require this to be set.
  161.  
  162.     Factor to Estimate File Transfer Time -- This is the decimal number used by
  163.     RBBS-PC  to estimate  the elapse time  to download  a file.  The higher the
  164.     number, the faster the protocol and the lower the time estimate.   Standard
  165.     equivalents in RBBS-PC are:
  166.  
  167.          Ascii ......... 0.92
  168.          Xmodem ........ 0.78
  169.          XmodemCRC ..... 0.78
  170.          Kermit ........ 0.78
  171.          Ymodem ........ 0.87
  172.          Imodem ........ 0.90
  173.          YmodemG ....... 0.95
  174.          Windowed xmodem 0.78
  175.  
  176.     If no value is specified, a default of 0.87 will be used.
  177.  
  178.     RBBS-PC "Macro" to  Invoke Before Protocol --  This is the RBBS-PC  "macro"
  179.     (i.e. a series of standard RBBS-PC commands) to invoke  before invoking the
  180.     protocol.  It can be used  to display special messages, to delay the  start
  181.     of  the protocol,  or  to  prompt for  special  information passed  to  the
  182.     protocol.
  183.  
  184.     Method  for  Checking  Transfer's Success  --  This  is  required only  for
  185.     external protocols.   This parameter indicates  how RBBS-PC is to  detect a
  186.     file transfer's failure.  The format is "x=y=z" where:
  187.          x    is which parameter tells whether the transfer was successful,
  188.          y    is the string which indicates failure, and
  189.          z    is  an optional parameter  telling RBBS-PC  whether to  write out
  190.               information needed when DOORing  to a protocol in advance  of the
  191.               file exchange.
  192.  
  193.  
  194.  
  195.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                    20-4
  196.  
  197.  
  198.     For QMXFER.EXE  from John Friel and the Forbin Project, this would be "4=F"
  199.     - meaning the 4th parameter indicates failure if it begins with "F".
  200.  
  201.     For Zmodem as implemented  in DSZ from Omen Technologies, the proper choice
  202.     depends on  whether SHELLing  or DOORing is  used.    For SHELLing,  put in
  203.     "1=E" to  indicate that the first  parameter uses "E" to  indicate an error
  204.     has occurred.   For DOORing,  put in  "4=E=A" to indicate  that the  fourth
  205.     parameter uses "E" when an error has occurred.  The "=A" means that RBBS-PC
  206.     is to  do an advance  write of the  filename and protocol  used.   DSZ then
  207.     appends its error report to the log file.   To the file "XFER-" plus node #
  208.     plus ".DEF" RBBS-PC will write out a line containing "<filename>,,<protocol
  209.     letter>".  Omitting an "=" causes a default to "4=F".   The file checked is
  210.     "XFER-" plus the node number plus the extension "DEF".   On node 1 the file
  211.     checked is "XFER-1.DEF".
  212.  
  213.     Template  to Use  for Downloading  -- This  is required  only for  external
  214.     protocols.  It tells RBBS-PC how to invoke a download.  See section 20.2.
  215.  
  216.     Template to  Use  for  Uploading --  This  is required  only  for  external
  217.     protocols.  It tells RBBS-PC how to invoke an upload.
  218.  
  219.     20.2 Calling external protocols using "templates"
  220.     -------------------------------------------------
  221.     A "template" is used to inform  RBBS-PC how to invoke an external protocol.
  222.     The  first  word of  the template  must be  the  file name  (including file
  223.     extension) of the program to invoke.   RBBS-PC will check to make sure that
  224.     the file exists.  If the file does not exist, the protocol will not be made
  225.     available to the caller.
  226.  
  227.     RBBS-PC will dynamically substitute values for pre-defined strings inside a
  228.     "template".   Each supported  string is enclosed  in square brackets.   The
  229.     strings supported include:
  230.  
  231.     [n]       where n is a positive integer.  Substitutes value in a work array
  232.               Macros  can store the prompted values in specific elements in the
  233.               array.
  234.  
  235.     [FILE]    Name of the file (FILE.NAME$) to be transferred.
  236.  
  237.     [BAUD]    Baud rate.  Speed at which the caller dialed RBBS-PC.
  238.  
  239.     [PARITY]  Parity used by the caller.
  240.  
  241.     [PORT]    DOS device name for the communications port to be used for the
  242.               file transfer (COM1,COM2, etc.).
  243.  
  244.     [PORT#]   Number  of  the  communications port  to  be  used  for the  file
  245.               transfer (1,2,3, etc.).
  246.  
  247.     [NODE]    Number of the RBBS-PC node invoking the file transfer (1,2,3,
  248.               etc.).
  249.  
  250.     [PROTO]   Letter of the protocol for the file transfer.
  251.  
  252.     Everything else in a template will be passed intact.   If the external file
  253.     transfer  is to be invoked via a SHELL, it is recommended that the external
  254.     file  transfer  program  be SHELLed  to  directly.   If  the  external file
  255.     transfer is to be invoked via a DOOR, it can be either
  256.  
  257.  
  258.  
  259.     RBBS-PC's STANDARD INTERFACE FOR PROTOCOL DRIVERS                      20-5
  260.  
  261.  
  262.       1) DOORed to directly using the same template as for SHELLing, or
  263.  
  264.       2) DOORed  to  indirectly via  a .BAT  file  with the  command parameters
  265.          passed  to it by RBBS-PC.  For example, a "door" for QMXFER might have
  266.          a download template of:
  267.  
  268.     "RBBSQM.BAT [FILE] [PORT] [BAUD] [PROTO]"
  269.  
  270.     and the file RBBSQM.BAT have the following in it:
  271.  
  272.               C:QMXFER.COM -s -f %1 -l %2 -c -b %3 -p %4
  273.  
  274.     DOS  substitutes the passed parameters for the variables beginning with the
  275.     percent  sign.  .BAT files are needed  if additional programs to run before
  276.     or after the actual file transfer.
  277.  
  278.     The following examples  should provide  some help in  understanding how  to
  279.     invoke external protocols:
  280.  
  281.     Example #1:
  282.  
  283.     Z)ippy,5,S,8,,,,,0.98,,,"c:\utl\zippy -s [FILE]","c:\utl\zippy -r [FILE]"
  284.  
  285.     Can be interpreted to be:
  286.          used "Z" as invoking letter,
  287.          put "Z)ippy" in the prompt,
  288.          the minimum security to use this protocol is 5,
  289.          the protocol will be invoked via a SHELL command,
  290.          an 8-bit connection is required,
  291.          estimate the download time as 0.98 times as fast as normal,
  292.          use normal RBBS-PC type of report to check for a successful transfer,
  293.          invoke the protocol for downloads using the following string:
  294.               "c:\utl\zippy -s [FILE]"
  295.          and invoke the protocol for uploads using the following string:
  296.               "c:\utl\zmodem -r [FILE]"
  297.          where the file name is substituted for "[FILE]" in either case.
  298.  
  299.     Example #2:
  300.  
  301.     X)modem,5,IX,8,,,128,,0.8,,,,
  302.  
  303.     Can be interpreted to be:
  304.          used "X" as invoking letter,
  305.          put "X)modem" in the prompt,
  306.          the minimum security to use this protocol is 5,
  307.          the protocol is an internal RBBS-PC protocol,
  308.          an 8-bit connection is required, and
  309.          estimate the download time as 0.8 times as fast as normal.
  310.  
  311.     20.3 Parameters Returned by a Protocol Driver
  312.     ---------------------------------------------
  313.     All  protocol drivers  are expected  to return  information about  the file
  314.     transfer in a file named XFER-xx.DEF where  the value for xx is the node ID
  315.     (1 to 36).  If the protocol cannot accommodate this minimal requirement, it
  316.     can still  be used by telling RBBS-PC to indicate file transfers are always
  317.     successful -- section 20.1, parameter 8.
  318.  
  319.     The  one item  of  information  RBBS-PC requires  to  be returned  from  an
  320.     external protocol drive is whether or not the file transfer was successful.
  321.  
  322.  
  323.  
  324.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                    20-6
  325.  
  326.  
  327.     The  failure indicator  MUST  BE  the  first  character  of  any  specified
  328.     parameter in the file XFER-xx.DEF.  To show that file transfer failures are
  329.     indicated  by   the  first  parameter  and  the  letter  "E"  in  the  file
  330.     XFER-xx.DEF, parameter 11 (as  described in section 20.1) would  be written
  331.     as "1=E".  To show that file  transfer failures are indicated by the fourth
  332.     parameter and the letter "F",  parameter 11 (as described in section  20.1)
  333.     would be written as "4=F".
  334.  
  335.     No  other information is required  when SHELLing to  external file transfer
  336.     protocols.  However, when  DOORing to external file transfer  protocols the
  337.     log file for the transfer MUST HAVE the file name as the first parameter.
  338.  
  339.     Protocol drivers that do not have the  file name as the first parameter can
  340.     still be used by telling RBBS-PC to write out three  parameters (file name,
  341.     an empty parameter, and  the letter of the  file transfer protocol)  before
  342.     invoking the  external file protocol.   This is done by  using parameter 11
  343.     (as described in section 20.1).  As an example, to DOOR to an external file
  344.     transfer  protocol  that indicates  a file  transfer  failure by  using the
  345.     letter "F" in the fourth parameter, but which does not return the file name
  346.     used, parameter  11 (as  described in  section 20.1)  would  be written  as
  347.     "4=F=A".   The external protocol would  then append its own  information to
  348.     the log file.
  349.  
  350.     20.4 The Protocol Drivers Tested With RBBS-PC
  351.     ---------------------------------------------
  352.     RBBS-PC has been tested with the following protocol drivers:
  353.  
  354.     CLINK     From  System  Enhancement  Associates.     Supports  batch   file
  355.               transfers,   but  requires  that   transfers  always  be  assumed
  356.               successful.
  357.  
  358.     DSZ       From Omen Technologies.   Supports Ymodem, Ymodem Batch, YmodemG,
  359.               and  Zmodem.  YmodemG requires a "reliable" connection.  DSZ logs
  360.               the results  of the file  transfers to  a file  specified in  the
  361.               environment variable  DSZLOG.   Therefore, the AUTOEXEC.BAT  file
  362.               for an RBBS-PC that uses DSZ should specify
  363.  
  364.                    "SET DSZLOG=XFER-x.DEF"
  365.  
  366.               where  x is the  node number.   DSZ seems unable  to create a log
  367.               file whenever a drive  or path is specified.   If invoking ZMODEM
  368.               via the  DOOR mechanism, use  the "=A" option  at the end  of the
  369.               success  method check so that RBBS-PC will append the information
  370.               to  the DSZ  log it needs  and DSZ  will then  append the success
  371.               report.     In  a   multi-user  environment  where   a  different
  372.               environment variable for each node can not be specified (i.e. all
  373.               nodes  must  share  the same  DSZ  log  file),  specify that  all
  374.               transfers are always successful for protocols handled via DSZ.
  375.  
  376.     MLINK     MEGALINK protocol supports batch file transfers but requires that
  377.               transfers always be assumed successful.
  378.  
  379.     PC-KERMIT from Columbia University.  PCKERMIT.EXE is supplied by The Source
  380.               as  a  public  service  and consists  of  sliding  window  KERMIT
  381.               protocol.  The  development  of  "windowing"  within  the  KERMIT
  382.               architecture  (i.e. Super  KERMIT) was funded  by The  Source and
  383.               implemented by Larry Jordan and Jan van der Eijk.
  384.  
  385.  
  386.  
  387.     RBBS-PC's STANDARD INTERFACE FOR PROTOCOL DRIVERS                      20-7
  388.  
  389.  
  390.               Columbia University holds the  copyright and maintains the Kermit
  391.               protocol. Like  RBBS-PC, Columbia University allows  KERMIT to be
  392.               passed along  to others  and "ask  only that profit  not be  your
  393.               goal, credit be given where  it is due, and that new  material be
  394.               sent  back  to us  so  that  we  can  maintain a  definitive  and
  395.               comprehensive set of KERMIT implementations".
  396.  
  397.               PCKERMIT.EXE is not a terminal program.  It simply implements the
  398.               Kermit protocol, including the sliding window extension.  It will
  399.               work  with older  "Kermit Classic"  implementations as  well, via
  400.               automatic   negotiation  between   the   two   Kermit   programs.
  401.               PCKERMIT.EXE  runs  as a  "one-shot"  execution  then returns  to
  402.               RBBS-PC.  PCKERMIT  does not  establish a carrier  with a  remote
  403.               system.    The  connection  is  established  by  RBBS-PC.    File
  404.               transfers must always be assumed successful.
  405.  
  406.     QMXFER    is   supplied  by  The  Forbin   Project.    It  supports  XMODEM
  407.               (checksum), XMODEM  (CRC), YMODEM, YMODEMG, and  IMODEM.  YMODEMG
  408.               and IMODEM  are designed to  work when the  link between the  two
  409.               modems  is "error free" (i.e.  both modems have  the MNP protocol
  410.               built  in).   QMXFER.COM  runs as  a  "one-shot" execution,  then
  411.               returns to RBBS-PC.   QMXFER does not establish a carrier  with a
  412.               remote system.  The  connection is established by RBBS-PC.   File
  413.               transfer failures are indicated by an "F" in the fourth parameter
  414.               of the log file returned to RBBS-PC.
  415.  
  416.     WXMODEM   is supplied by The Forbin Project, and supports the window XMODEM
  417.               protocol  designed  by  Pete  Boswell.    Like all  of  RBBS-PC's
  418.               protocol drivers, WXMODEM.COM runs as a "one-shot" execution then
  419.               returns  to RBBS-PC.  WXMODEM does not establish a carrier with a
  420.               remote system.  The  connection is established by RBBS-PC.   File
  421.               transfer failures are indicated by an "F" in the fourth parameter
  422.               of the log file returned to RBBS-PC.
  423.  
  424.     Other protocols tested with RBBS-PC include SuperK, Jmodem and Puma.
  425.  
  426.